OpenEdge Development:<br />Progress Dynamics Advanced Development How objects are instantiated using prepareInstance

This section outlines the steps necessary to bring a container window or other container object into being at run time using the cached Repository information. If you want to understand more about exactly how containers are created, you can study the relevant code in the ADM2 support procedure src/adm2/container.p, as well as the dynamic window procedure ry/uib/rydyncontw.w.

When an object is launched, whether it is by launchContainer, constructObject, or just from the editor, a Repository Manager function called prepareInstance is called from the main block of the base ADM property include file smrtprop.i. This is just about the earliest that anything can run in the ADM world, and the call must be as early as possible so that the ADMProps temp-table, where all of each object’s attributes are held, is built as soon as possible.

The prepareInstance function attempts to determine the logical name of the object being launched, since this is what is used to retrieve the objects from the Repository. It does this by calling a function called getCurrentLogicalName in the procedure that launched the object being run. This function is defined in the Session Manager (which contains launchContainer, the primary starting point for objects run from the menu), the dynamic container procedure rydyncontw.w, the dynamic viewer rydynviewv.w, and the dynamic TreeView rydyntreew.w.

The value returned by getCurrentLogicalName can be in one of two forms (errors and blanks excepted):

The actual value of the object’s logical name, equivalent to the Repository field ryc_smartobject.object_filename.

A value in the form of InstanceId=<value>.

If there is a single valid object name, rather than the form InstanceId=*, the relevant data is retrieved from either the cache or the Repository, using cacheObjectOnClient. Once this data is returned, the ADMProps temp-table is constructed based on the object's attribute buffer.

The InstanceID ADM attribute is set at this point. Each object that is run will have a unique InstanceID.

The reason for the two different forms of the return value of getCurrentLogicalName is that when you are instantiating a master object (which would be the container of other objects), the function returns the actual logical object name that you want to retrieve. When you want to retrieve object instances within a container, the function returns the InstanceId= form. This is because there might be many records with the contained instance’s logical object name. If a toolbar is placed on many windows, for example, there will be one record for the master and one for each object instance. By contrast, there can only be one record with a particular instance ID (tRecordIdentifier).

Consider a window called window1. It contains an SDO called fullo1 and a browser called browser1. If you launch window1 from a menu, launchContainer sets the CurrentLogicalName value to window1 before running the dynamic container object (the procedure rydyncontw.w). When rydyncontw.w runs, it picks up the logical object name and passes that into the function cacheObjectOnClient, which then retrieves into the cache the five sets of object records that make up the window:

window1 itself (the master object).

fullo1 (the master and instance of fullo1 on window1).

browser1 (the master and instance of fullo1 on window1).

Two standard ADM2 support procedures in the container class have been extended for Progress Dynamics to create dynamic containers from cached Repository data as opposed to simply running static procedure objects, as would be the case with a standard Version 9 ADM2 application. These are createobjects and constructObject.

As window1 in created, the ADM container startup code runs createobjects. This procedure has the responsibility of creating the objects that are to appear on window1. createobjects retrieves the InstanceID property of window1 and then makes sure that the correct cache_Object record is available, by calling getCacheObjectBuffer and passing in the InstanceID. This InstanceID is used to build a query to loop through all of the contained instances (... WHERE tContainerRecordIdentifier = dInstanceID).

The framework then runs constructObject to construct browser1 and fullo1. The code must make sure that the correct set of attributes is used for the instance of each object on window1, so it sets the CurrentLogicalName to Instanceid= since this is already available.